home *** CD-ROM | disk | FTP | other *** search
/ Clickx 115 / Clickx 115.iso / software / tools / windows / tails-i386-0.16.iso / live / filesystem.squashfs / usr / lib / perl5 / Glib / Object.pod < prev    next >
Encoding:
Text File  |  2012-02-20  |  12.0 KB  |  606 lines

  1. =head1 NAME
  2.  
  3. Glib::Object -  Bindings for GObject
  4.  
  5. =cut
  6.  
  7. =for position DESCRIPTION
  8.  
  9. =head1 DESCRIPTION
  10.  
  11. GObject is the base object class provided by the gobject library.  It provides
  12. object properties with a notification system, and emittable signals.
  13.  
  14. Glib::Object is the corresponding Perl object class.  Glib::Objects are
  15. represented by blessed hash references, with a magical connection to the
  16. underlying C object.
  17.  
  18. =head2 get and set
  19.  
  20. Some subclasses of C<Glib::Object> override C<get> and C<set> with methods
  21. more useful to the subclass, for example C<Gtk2::TreeModel> getting and
  22. setting row contents.
  23.  
  24. This is usually done when the subclass has no object properties.  Any object
  25. properties it or a further subclass does have can always be accessed with
  26. C<get_property> and C<set_property> (together with C<find_property> and
  27. C<list_properties> to enquire about them).
  28.  
  29. Generic code for any object subclass can use the names C<get_property> and
  30. C<set_property> to be sure of getting the object properties as such.
  31.  
  32. =cut
  33.  
  34.  
  35.  
  36. =head1 HIERARCHY
  37.  
  38.   Glib::Object
  39.  
  40.  
  41.  
  42. =cut
  43.  
  44. =for object Glib::Object Bindings for GObject
  45. =cut
  46.  
  47.  
  48.  
  49.  
  50. =head1 METHODS
  51.  
  52. =head2 object = $class->B<new> (...)
  53.  
  54. =over
  55.  
  56. =item * ... (list) key/value pairs, property values to set on creation
  57.  
  58. =back
  59.  
  60.  
  61.  
  62.  
  63. Instantiate a Glib::Object of type I<$class>.  Any key/value pairs in
  64. I<...> are used to set properties on the new object; see C<set>.
  65. This is designed to be inherited by Perl-derived subclasses (see
  66. L<Glib::Object::Subclass>), but you can actually use it to create
  67. any GObject-derived type.
  68.  
  69.  
  70. =head2 scalar = Glib::Object-E<gt>B<new_from_pointer> ($pointer, $noinc=FALSE)
  71.  
  72. =over
  73.  
  74. =item * $pointer (unsigned) a C pointer value as an integer.
  75.  
  76. =item * $noinc (boolean) if true, do not increase the GObject's reference count when creating the Perl wrapper.  this typically means that when the Perl wrapper will own the object.  in general you don't want to do that, so the default is false.
  77.  
  78. =back
  79.  
  80.  
  81.  
  82.  
  83. Create a Perl Glib::Object reference for the C object pointed to by I<$pointer>.
  84. You should need this I<very> rarely; it's intended to support foreign objects.
  85.  
  86. NOTE: the cast from arbitrary integer to GObject may result in a core dump without
  87. warning, because the type-checking macro G_OBJECT() attempts to dereference the
  88. pointer to find a GTypeClass structure, and there is no portable way to validate
  89. the pointer.
  90.  
  91.  
  92. =head2 unsigned = $object-E<gt>B<get_data> ($key)
  93.  
  94. =over
  95.  
  96. =item * $key (string) 
  97.  
  98. =back
  99.  
  100.  
  101. Fetch the integer stored under the object data key I<$key>.  These values do not
  102. have types; type conversions must be done manually.  See C<set_data>.
  103.  
  104.  
  105. =head2 $object-E<gt>B<set_data> ($key, $data)
  106.  
  107. =over
  108.  
  109. =item * $key (string) 
  110.  
  111. =item * $data (scalar) 
  112.  
  113. =back
  114.  
  115.  
  116. GObject provides an arbitrary data mechanism that assigns unsigned integers
  117. to key names.  Functionality overlaps with the hash used as the Perl object
  118. instance, so we strongly recommend you use hash keys for your data storage.
  119. The GObject data values cannot store type information, so they are not safe
  120. to use for anything but integer values, and you really should use this method
  121. only if you know what you are doing.
  122.  
  123.  
  124. =head2 pspec or undef = $object_or_class_name->B<find_property> ($name)
  125.  
  126. =over
  127.  
  128. =item * $name (string) 
  129.  
  130. =back
  131.  
  132. Find the definition of object property I<$name> for I<$object_or_class_name>.
  133. Return C<undef> if no such property.  For
  134. the returned data see L<Glib::Object::list_properties>.
  135.  
  136. =head2 $object-E<gt>B<freeze_notify> 
  137.  
  138.  
  139. Stops emission of "notify" signals on I<$object>. The signals are queued
  140. until C<thaw_notify> is called on I<$object>.
  141.  
  142.  
  143. =head2 $object-E<gt>B<get> (...)
  144.  
  145. =over
  146.  
  147. =item * ... (list) list of property names
  148.  
  149. =back
  150.  
  151.  
  152. Alias for C<get_property> (see L</get and set> above).
  153.  
  154.  
  155. =head2 $object->B<set> (key => $value, ...)
  156.  
  157. =over
  158.  
  159. =item * ... (list) key/value pairs
  160.  
  161. =back
  162.  
  163.  
  164. Alias for C<set_property> (see L</get and set> above).
  165.  
  166.  
  167. =head2 list = $object_or_class_name->B<list_properties>
  168.  
  169. =over
  170.  
  171. =back
  172.  
  173. List all the object properties for I<$object_or_class_name>; returns them as
  174. a list of hashes, containing these keys:
  175.  
  176. =over
  177.  
  178. =item name
  179.  
  180. The name of the property
  181.  
  182. =item type
  183.  
  184. The type of the property
  185.  
  186. =item owner_type
  187.  
  188. The type that owns the property
  189.  
  190. =item descr
  191.  
  192. The description of the property
  193.  
  194. =item flags
  195.  
  196. The Glib::ParamFlags of the property
  197.  
  198. =back
  199.  
  200.  
  201. =head2 $object-E<gt>B<notify> ($property_name)
  202.  
  203. =over
  204.  
  205. =item * $property_name (string) 
  206.  
  207. =back
  208.  
  209.  
  210. Emits a "notify" signal for the property I<$property> on I<$object>.
  211.  
  212.  
  213. =head2 gpointer = $object-E<gt>B<get_pointer> 
  214.  
  215.  
  216. Complement of C<new_from_pointer>.
  217.  
  218.  
  219. =head2 $object-E<gt>B<get_property> (...)
  220.  
  221. =over
  222.  
  223. =back
  224.  
  225.  
  226. Fetch and return the values for the object properties named in I<...>.
  227.  
  228.  
  229. =head2 $object->B<set_property> (key => $value, ...)
  230.  
  231. =over
  232.  
  233. =back
  234.  
  235.  
  236. Set object properties.
  237.  
  238.  
  239. =head2 unsigned = $object_or_class_name-E<gt>B<signal_add_emission_hook> ($detailed_signal, $hook_func, $hook_data=undef)
  240.  
  241. =over
  242.  
  243. =item * $detailed_signal (string) of the form "signal-name::detail"
  244.  
  245. =item * $hook_func (subroutine) 
  246.  
  247. =item * $hook_data (scalar) 
  248.  
  249. =back
  250.  
  251. Add an emission hook for a signal.  The hook will be called for any emission
  252. of that signal, independent of the instance.  This is possible only for
  253. signals which don't have the C<G_SIGNAL_NO_HOOKS> flag set.
  254.  
  255. The I<$hook_func> should be reference to a subroutine that looks something
  256. like this:
  257.  
  258.   sub emission_hook {
  259.       my ($invocation_hint, $parameters, $hook_data) = @_;
  260.       # $parameters is a reference to the @_ to be passed to
  261.       # signal handlers, including the instance as $parameters->[0].
  262.       return $stay_connected;  # boolean
  263.   }
  264.  
  265. This function returns an id that can be used with C<remove_emission_hook>.
  266.  
  267. Since 1.100.
  268.  
  269. =head2 list = $instance-E<gt>B<signal_chain_from_overridden> (...)
  270.  
  271. =over
  272.  
  273. =item * ... (list) 
  274.  
  275. =back
  276.  
  277.  
  278. Chain up to an overridden class closure; it is only valid to call this from
  279. a class closure override.
  280.  
  281. Translation: because of various details in how GObjects are implemented,
  282. the way to override a virtual method on a GObject is to provide a new "class
  283. closure", or default handler for a signal.  This happens when a class is
  284. registered with the type system (see Glib::Type::register and
  285. L<Glib::Object::Subclass>).  When called from inside such an override, this
  286. method runs the overridden class closure.  This is equivalent to calling
  287. $self->SUPER::$method (@_) in normal Perl objects.
  288.  
  289.  
  290. =head2 unsigned = $instance-E<gt>B<signal_connect> ($detailed_signal, $callback, $data=undef)
  291.  
  292. =over
  293.  
  294. =item * $detailed_signal (string) 
  295.  
  296. =item * $callback (subroutine) 
  297.  
  298. =item * $data (scalar) arbitrary data to be passed to each invocation of I<callback>
  299.  
  300. =back
  301.  
  302.  
  303.  
  304.  
  305. Register I<callback> to be called on each emission of I<$detailed_signal>.
  306. Returns an identifier that may be used to remove this handler with
  307. C<< $object->signal_handler_disconnect >>.
  308.  
  309.  
  310. =head2 unsigned = $instance-E<gt>B<signal_connect_after> ($detailed_signal, $callback, $data=undef)
  311.  
  312. =over
  313.  
  314. =item * $detailed_signal (string) 
  315.  
  316. =item * $callback (scalar) 
  317.  
  318. =item * $data (scalar) 
  319.  
  320. =back
  321.  
  322.  
  323. Like C<signal_connect>, except that I<$callback> will be run after the default
  324. handler.
  325.  
  326.  
  327. =head2 unsigned = $instance-E<gt>B<signal_connect_swapped> ($detailed_signal, $callback, $data=undef)
  328.  
  329. =over
  330.  
  331. =item * $detailed_signal (string) 
  332.  
  333. =item * $callback (scalar) 
  334.  
  335. =item * $data (scalar) 
  336.  
  337. =back
  338.  
  339.  
  340. Like C<signal_connect>, except that I<$data> and I<$object> will be swapped
  341. on invocation of I<$callback>.
  342.  
  343.  
  344. =head2 retval = $object->B<signal_emit> ($name, ...)
  345.  
  346. =over
  347.  
  348. =item * $name (string) the name of the signal
  349.  
  350. =item * ... (list) any arguments to pass to handlers.
  351.  
  352. =back
  353.  
  354.  
  355.  
  356.  
  357.  
  358. Emit the signal I<name> on I<$object>.  The number and types of additional
  359. arguments in I<...> are determined by the signal; similarly, the presence
  360. and type of return value depends on the signal being emitted.
  361.  
  362.  
  363. =head2 $ihint = $instance->B<signal_get_invocation_hint>
  364.  
  365. Get a reference to a hash describing the innermost signal currently active
  366. on C<$instance>.  Returns undef if no signal emission is active.  This
  367. invocation hint is the same object passed to signal emission hooks, and
  368. contains these keys:
  369.  
  370. =over
  371.  
  372. =item signal_name
  373.  
  374. The name of the signal being emitted.
  375.  
  376. =item detail
  377.  
  378. The detail passed on for this emission.  For example, a C<notify> signal will
  379. have the property name as the detail.
  380.  
  381. =item run_type
  382.  
  383. The current stage of signal emission, one of "run-first", "run-last", or
  384. "run-cleanup".
  385.  
  386. =back
  387.  
  388.  
  389. =head2 $object-E<gt>B<signal_handler_block> ($handler_id)
  390.  
  391. =over
  392.  
  393. =item * $handler_id (unsigned) 
  394.  
  395. =back
  396.  
  397. =head2 $object-E<gt>B<signal_handler_disconnect> ($handler_id)
  398.  
  399. =over
  400.  
  401. =item * $handler_id (unsigned) 
  402.  
  403. =back
  404.  
  405. =head2 boolean = $object-E<gt>B<signal_handler_is_connected> ($handler_id)
  406.  
  407. =over
  408.  
  409. =item * $handler_id (unsigned) 
  410.  
  411. =back
  412.  
  413. =head2 $object-E<gt>B<signal_handler_unblock> ($handler_id)
  414.  
  415. =over
  416.  
  417. =item * $handler_id (unsigned) 
  418.  
  419. =back
  420.  
  421. =head2 integer = $instance-E<gt>B<signal_handlers_block_by_func> ($func, $data=undef)
  422.  
  423. =over
  424.  
  425. =item * $func (subroutine) function to block
  426.  
  427. =item * $data (scalar) data to match, ignored if undef
  428.  
  429. =back
  430.  
  431.  
  432.  
  433. =head2 integer = $instance-E<gt>B<signal_handlers_disconnect_by_func> ($func, $data=undef)
  434.  
  435. =over
  436.  
  437. =item * $func (subroutine) function to block
  438.  
  439. =item * $data (scalar) data to match, ignored if undef
  440.  
  441. =back
  442.  
  443.  
  444.  
  445. =head2 integer = $instance-E<gt>B<signal_handlers_unblock_by_func> ($func, $data=undef)
  446.  
  447. =over
  448.  
  449. =item * $func (subroutine) function to block
  450.  
  451. =item * $data (scalar) data to match, ignored if undef
  452.  
  453. =back
  454.  
  455.  
  456.  
  457. =head2 scalar = $object_or_class_name-E<gt>B<signal_query> ($name)
  458.  
  459. =over
  460.  
  461. =item * $name (string) 
  462.  
  463. =back
  464.  
  465. Look up information about the signal I<$name> on the instance type
  466. I<$object_or_class_name>, which may be either a Glib::Object or a package
  467. name.
  468.  
  469. See also C<Glib::Type::list_signals>, which returns the same kind of
  470. hash refs as this does.
  471.  
  472. Since 1.080.
  473.  
  474. =head2 $object_or_class_name-E<gt>B<signal_remove_emission_hook> ($signal_name, $hook_id)
  475.  
  476. =over
  477.  
  478. =item * $signal_name (string) 
  479.  
  480. =item * $hook_id (unsigned) 
  481.  
  482. =back
  483.  
  484. Remove a hook that was installed by C<add_emission_hook>.
  485.  
  486. Since 1.100.
  487.  
  488. =head2 $instance-E<gt>B<signal_stop_emission_by_name> ($detailed_signal)
  489.  
  490. =over
  491.  
  492. =item * $detailed_signal (string) 
  493.  
  494. =back
  495.  
  496. =head2 $object-E<gt>B<thaw_notify> 
  497.  
  498.  
  499. Reverts the effect of a previous call to C<freeze_notify>. This causes all
  500. queued "notify" signals on I<$object> to be emitted.
  501.  
  502.  
  503. =head2 boolean = Glib::Object-E<gt>B<set_threadsafe> ($threadsafe)
  504.  
  505. =over
  506.  
  507. =item * $threadsafe (boolean) 
  508.  
  509. =back
  510.  
  511. Enables/disables threadsafe gobject tracking. Returns whether or not tracking
  512. will be successful and thus whether using perl ithreads will be possible.
  513.  
  514. =head2 $object-E<gt>B<tie_properties> ($all=FALSE)
  515.  
  516. =over
  517.  
  518. =item * $all (boolean) if FALSE (or omitted) tie only properties for this object's class, if TRUE tie the properties of this and all parent classes.
  519.  
  520. =back
  521.  
  522.  
  523. A special method available to Glib::Object derivatives, it uses perl's tie
  524. facilities to associate hash keys with the properties of the object. For
  525. example:
  526.  
  527.   $button->tie_properties;
  528.   # equivilent to $button->set (label => 'Hello World');
  529.   $button->{label} = 'Hello World';
  530.   print "the label is: ".$button->{label}."\n";
  531.  
  532. Attempts to write to read-only properties will croak, reading a write-only
  533. property will return '[write-only]'.
  534.  
  535. Care must be taken when using tie_properties with objects of types created with
  536. Glib::Object::Subclass as there may be clashes with existing hash keys that
  537. could cause infinite loops. The solution is to use custom property get/set
  538. functions to alter the storage locations of the properties.
  539.  
  540.  
  541.  
  542. =cut
  543.  
  544.  
  545. =head1 SIGNALS
  546.  
  547. =over
  548.  
  549. =item B<notify> (Glib::Object, Glib::ParamSpec)
  550.  
  551. =back
  552.  
  553.  
  554.  
  555. =cut
  556.  
  557.  
  558. =head1 ENUMS AND FLAGS
  559.  
  560. =head2 flags Glib::SignalFlags
  561.  
  562.  
  563.  
  564. =over
  565.  
  566. =item * 'run-first' / 'G_SIGNAL_RUN_FIRST'
  567.  
  568. =item * 'run-last' / 'G_SIGNAL_RUN_LAST'
  569.  
  570. =item * 'run-cleanup' / 'G_SIGNAL_RUN_CLEANUP'
  571.  
  572. =item * 'no-recurse' / 'G_SIGNAL_NO_RECURSE'
  573.  
  574. =item * 'detailed' / 'G_SIGNAL_DETAILED'
  575.  
  576. =item * 'action' / 'G_SIGNAL_ACTION'
  577.  
  578. =item * 'no-hooks' / 'G_SIGNAL_NO_HOOKS'
  579.  
  580. =back
  581.  
  582.  
  583.  
  584.  
  585. =cut
  586.  
  587.  
  588. =head1 SEE ALSO
  589.  
  590. L<Glib>
  591.  
  592.  
  593. =cut
  594.  
  595.  
  596. =head1 COPYRIGHT
  597.  
  598. Copyright (C) 2003-2011 by the gtk2-perl team.
  599.  
  600. This software is licensed under the LGPL.  See L<Glib> for a full notice.
  601.  
  602.  
  603.  
  604. =cut
  605.  
  606.